<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head><title>Introduction</title>

</head>

<body>
<p>Authors: Aslak Hellesoy, Jon Tirsen</p>

<h2>Basics</h2>

<p>This is a quick introduction to PicoContainer's most important
    features. Read through it to get an idea of what PicoContainer is and
    isn't. </p>

<p>PicoContainer's most important feature is its ability to
    instantiate arbitrary objects. This is done through its API, which is
    similar to a hash table. You can put java.lang.Class objects in and get
    object instances back.</p>

<p>Example:</p>

<div class="source">
    <div>
<pre>MutablePicoContainer pico = new DefaultPicoContainer();
pico.addComponent(ArrayList.class);
List list = (List) pico.getComponent(ArrayList.class);</pre>
    </div>
</div>
<p>(i)<a
        href="http://www.picocontainer.org/picocontainer/latest/picocontainer/apidocs/org/picocontainer/MutablePicoContainer.html">MutablePicoContainer
    API<sup><img class="rendericon" src="/images/icons/linkext7.gif" alt="" align="middle" border="0" height="7"
                 width="7"></sup></a></p>

<p>This code does the same as this:</p>

<div class="source">
    <div>
        <pre>List list = new ArrayList();</pre>
    </div>
</div>
<p>With a trivial example such as this there is no point in using
    PicoContainer. This was just to illustrate the basic API. PicoContainer
    becomes useful with larger number of classes and interfaces having
    complex dependencies between each other:</p>
<table>
    <tbody>
        <tr>
            <th> Complex Dependencies</th>
            <th> Juicer Example</th>
        </tr>
        <tr>
            <td><img src="images/complex-dependencies.png" align="middle" border="0"></td>
            <td><img src="images/juicer-peeler-peelable.png" align="middle" border="0"></td>
        </tr>
    </tbody>
</table>
<p>(Green means class, Yellow means interface).

    PicoContainer identifies dependencies by looking at the constructors of
    registered classes (<a href="constructor-injection.html" title="Constructor Injection">Constructor Injection</a>).
    PicoContainer can also be though of as a generic factory that can be
    configured dynamically. PicoContainer is able to instantiate a complex
    graph of several interdependent objects.</p>

<h2>Write some simple classes and interfaces with dependencies</h2>

<p>The "Juicer Example" diagram above could translate to the
    following code (we added a concrete Peelable):</p>

<p><img src="images/apple-implements-peelable.png" align="middle" border="0"></p>

<div class="source">
    <div>
<pre>public interface Peelable {
 void peel();
}</pre>
    </div>
</div>
<div class="source">
    <div>
<pre>public class Apple implements Peelable {
 public void peel() {
 }
}</pre>
    </div>
</div>
<div class="source">
    <div>
<pre>public class Peeler implements Startable {
 private final Peelable peelable;

 public Peeler(Peelable peelable) {
 this.peelable = peelable;
 }

 public void start() {
 peelable.peel();
 }

 public void stop() {

 }
}</pre>
    </div>
</div>
<div class="source">
    <div>
<pre>public class Juicer {
 private final Peelable peelable;
 private final Peeler peeler;

 public Juicer(Peelable peelable, Peeler peeler) {
 this.peelable = peelable;
 this.peeler = peeler;
 }
}</pre>
    </div>
</div>
<p>(Note that this code suffers from the antipattern <a href="propagating-dependency-antipattern.html"
                                                        title="Propagating Dependency">Propagating Dependency</a>
    but let's not worry about that for now <img class="emoticon" src="/images/icons/emoticons/smile.gif" alt=""
                                                align="middle" border="0" height="20" width="20">)</p>

<h2>Assemble components</h2>

<p>You tell PicoContainer what classes to manage by registering
    them like this (the order of registration has no significance):</p>

<div class="source">
    <div>
<pre>MutablePicoContainer pico = new DefaultPicoContainer();
pico.addComponent(Apple.class);
pico.addComponent(Juicer.class);
pico.addComponent(Peeler.class);</pre>
    </div>
</div>
<p>(i)<a
        href="http://www.picocontainer.org/picocontainer/latest/picocontainer/apidocs/org/picocontainer/MutablePicoContainer.html">MutablePicoContainer
    API<sup><img class="rendericon" src="/images/icons/linkext7.gif" alt="" align="middle" border="0" height="7"
                 width="7"></sup></a></p>

<h2>Instantiate components</h2>

<p>You can tell PicoContainer to give you an instance of a class
    like this (provided it has been registered previously):</p>

<div class="source">
    <div>
        <pre>Juicer juicer = (Juicer) pico.getComponent(Juicer.class);</pre>
    </div>
</div>
<p>This will cause PicoContainer to do something similar to this
    behind the scenes (except that PicoContainer uses reflection):</p>

<div class="source">
    <div>
<pre>Peelable peelable = new Apple();
Peeler peeler = new Peeler(peelable);
Juicer juicer = new Juicer(peelable, peeler);
return juicer;</pre>
    </div>
</div>
<p><img class="emoticon" src="/images/icons/emoticons/information.gif" alt="" align="middle" border="0" height="16"
        width="16">
    Note how PicoContainer figures out that Apple is a Peelable, so that it
    can be passed to Peeler and Juicer's constructors.</p>

<h2>Container hierarchies</h2>

<p>PicoContainer provides a powerful alternative to the <a href="singleton-antipattern.html"
                                                           title="Singleton">Singleton</a>.
    With container hierarchies you can create singleton-like objects where
    you have fine grained control over the visibility scope of the
    instance. (The singleton pattern is static and global - it won't allow
    more than one instance, and it is visible from anywhere. Not nice when
    you try to build a large enterprise application from it).</p>

<p><img src="images/pico-hierarchy.png" align="middle" border="0"></p>

<p>A container (and its registered components) can get access to
    components registered in a parent container, but not vice-versa.
    Consider this example, using the classes from above:</p>

<p><img class="emoticon" src="/images/icons/emoticons/warning.gif" alt="" align="middle" border="0" height="16"
        width="16">

    THIS WON'T WORK! It is for illustration purposes only!

    <img class="emoticon" src="/images/icons/emoticons/warning.gif" alt="" align="middle" border="0" height="16"
         width="16"></p>

<div class="source">
    <div>
<pre>// Create x hierarchy of containers
MutablePicoContainer x = new DefaultPicoContainer();
MutablePicoContainer y = new DefaultPicoContainer( x );
MutablePicoContainer z = new DefaultPicoContainer( y );

// Assemble components
x.addComponent(Apple.class);
y.addComponent(Juicer.class);
z.addComponent(Peeler.class);

// Instantiate components
Peeler peeler = (Peeler) z.getComponent(Peeler.class);
// WON'T WORK! peeler will be null
peeler = (Peeler) x.getComponent(Peeler.class);
// WON'T WORK! This will throw an exception
Juicer juicer = (Juicer) y.getComponent(Juicer.class);</pre>
    </div>
</div>
<p>This can be visualised as follows:

    <img src="images/juicer-in-pico-hierarchy.png" align="middle" border="0"></p>

<p>Let's analyse what will happen here:</p>
<ul>
    <li>Line 12 will work fine. z will be able to resolve the
        dependencies for Peeler (which is Fruit) from the parent container.
    </li>
    <li>Line 14 will return null, as x can't see Peeler.</li>
    <li>Line 16 will throw an exception, since Juicer's dependency
        to Peeler can't be satisfied (z can't be seen by y).
    </li>
</ul>
<p><img class="emoticon" src="/images/icons/emoticons/warning.gif" alt="" align="middle" border="0" height="16"
        width="16">
    Since this obviously won't work, keep in mind that this was just an
    exercise to illustrate how container hierarchies work.

    <img class="emoticon" src="/images/icons/emoticons/information.gif" alt="" align="middle" border="0" height="16"
         width="16">
    For a more concrete example of the usage of container hierarchies, see <a href="http://www.picocontainer.org/web"
                                                                              rel="nofollow">PicoContainer Web
    <sup><img class="rendericon" src="/images/icons/linkext7.gif" alt="" align="middle" border="0" height="7" width="7"></sup></a>.
</p>

<h2>Lifecycle</h2>

<p>PicoContainer has support for <a href="lifecycle.html" title="Lifecycle">Lifecycle</a>. If your classes
    implement <a
        href="http://www.picocontainer.org/picocontainer/latest/picocontainer/apidocs/org/picocontainer/Startable.html">Startable<sup><img
        class="rendericon" src="/images/icons/linkext7.gif" alt="" align="middle" border="0" height="7" width="7"></sup></a>,
    you can control the
    lifecycle of all your objects with a simple method call on the
    container. The container will figure out the correct order of
    invocation of start()/stop() all the objects managed by the container.</p>

<p>Calling start() on the container will call start() on all
    container managed objects in the order of their instantiation. This
    means starting with the ones that have no dependencies, and ending with
    the ones that have dependencies on others:</p>
<table>
    <tbody>
        <tr>
            <th> MutablePicoContainer.start()</th>
            <th> MutablePicoContainer.stop()</th>
        </tr>
        <tr>
            <td><img src="images/start-container.png" align="middle" border="0"></td>
            <td><img src="images/stop-container.png" align="middle" border="0"></td>
        </tr>
    </tbody>
</table>
<p>Lifecycle also works for hierarchies of containers. Calling
    start() on a container with child containers will start all the
    containers in a breadth-first order, starting with itself. Likewise,
    calling stop() will call stop() on all containers in the hierarchy in a
    depth-first order. The pictures below show what happens when start()
    and stop() are called on a container with children.</p>
<table>
    <tbody>
        <tr>
            <th> MutablePicoContainer.start()</th>
            <th> MutablePicoContainer.stop()</th>
        </tr>
        <tr>
            <td><img src="images/start-hierarchy.png" align="middle" border="0"></td>
            <td><img src="images/stop-hierarchy.png" align="middle" border="0"></td>
        </tr>
    </tbody>
</table>
<p><img class="emoticon" src="/images/icons/emoticons/warning.gif" alt="" align="middle" border="0" height="16"
        width="16">
    In order for hierarchy-aware lifecycle to work, child containers must
    be registered as components in their parent container. Just creating a
    container with another one as a parent will <b>not</b>
    cause the parent container to know about the child container.</p>

<h3>Example</h3>

<div class="source">
    <div>
<pre>MutablePicoContainer parent = new DefaultPicoContainer(new Caching());
MutablePicoContainer child = new DefaultPicoContainer(parent);
// We must let the parent container know about the child container.
parent.addComponent(child);
// This will start the parent, which will start the child.
parent.start();</pre>
    </div>
</div>
<p><strong><img class="emoticon" src="/images/icons/emoticons/warning.gif" alt="warning" align="middle" border="0"
                height="16" width="16">
</strong>Lifecycle is really only going to work for
    PicoContainers that are also caching component instances. Caching was a
    default in PicoContainer 1.x, but is not for 2.x - be warned!</p>

<p><img class="emoticon" src="/images/icons/emoticons/warning.gif" alt="" align="middle" border="0" height="16"
        width="16">
    Calling lifecycle methods on a container that has a parent container
    will <b>not</b> propagate the lifecycle to the parent
    container. </p>

<p>Read more about lifecycle <a href="lifecycle.html" title="Lifecycle">here</a>.</p>

<h3>Contrasting Usage Styles </h3>

<p>With PicoContainer you add components and get instances out in
    two styles. </p>

<p>Classic bean style: </p>

<div class="source">
<pre>pico = new DefaultPicoContainer();
pico.addComponent(ComponentOneImpl.class) // by type
pico.addComponent(ComponentTwoImpl.class) // by type
pico.addComponent(new ComponentThreeImpl()) // by instance
pico.addComponent(ComponentFourImpl.class) // by type

ComponentFourImpl four = pico.getComponent(ComponentFourImpl.class);
</pre>
</div>
<p>Or you can use a <a href="http://www.martinfowler.com/bliki/FluentInterface.html">fluent</a>
    style if you want:</p>

<div class="source">
<pre>ComponentFour four = new DefaultPicoContainer()
 .addComponent(ComponentOne.class)
 .addComponent(ComponentTwo.class)
 .addComponent(new ComponentThree())
 .addComponent(ComponentFour.class)
 .getComponent(ComponentFour.class);</pre>
</div>
<h3>Where Next?</h3>
<span class="callout">
The <a href="injection.html">Dependency Injection</a>
page discusses the types of Dependency Injection, with examples
</span>

</body>
</html>